wfcqueue: document empty criterion

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>

diff --git a/urcu/static/wfcqueue.h b/urcu/static/wfcqueue.h
index 1200227f4d3f6ade1f118b47ec77d592b3a508b5..8774c0375eff1aa6cd458f39697cd1b7a39ef173 100644 (file)
--- a/urcu/static/wfcqueue.h
+++ b/urcu/static/wfcqueue.h
@@ -95,6 +95,13 @@ static inline void _cds_wfcq_init(struct cds_wfcq_head *head,
  * cds_wfcq_empty: return whether wait-free queue is empty.
  *
  * No memory barrier is issued. No mutual exclusion is required.
+ *
+ * We perform the test on head->node.next to check if the queue is
+ * possibly empty, but we confirm this by checking if the tail pointer
+ * points to the head node because the tail pointer is the linearisation
+ * point of the enqueuers. Just checking the head next pointer could
+ * make a queue appear empty if an enqueuer is preempted for a long time
+ * between xchg() and setting the previous node's next pointer.
  */
 static inline bool _cds_wfcq_empty(struct cds_wfcq_head *head,
                struct cds_wfcq_tail *tail)