From f94061a3df4c9eab9ac869a19e4228de54771fcb Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Mon, 8 Oct 2012 12:11:30 -0400 Subject: [PATCH] wfcqueue documentation: hint at for_each iterators Reported-by: Paolo Bonzini Signed-off-by: Mathieu Desnoyers --- urcu/static/wfcqueue.h | 13 +++++++++++-- urcu/wfcqueue.h | 13 +++++++++++-- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/urcu/static/wfcqueue.h b/urcu/static/wfcqueue.h index a989984..944ee88 100644 --- a/urcu/static/wfcqueue.h +++ b/urcu/static/wfcqueue.h @@ -48,8 +48,9 @@ extern "C" { * * Unless otherwise stated, the caller must ensure mutual exclusion of * queue update operations "dequeue" and "splice" (for source queue). - * Queue read operations "first" and "next" need to be protected against - * concurrent "dequeue" and "splice" (for source queue) by the caller. + * Queue read operations "first" and "next", which are used by + * "for_each" iterations, need to be protected against concurrent + * "dequeue" and "splice" (for source queue) by the caller. * "enqueue", "splice" (for destination queue), and "empty" are the only * operations that can be used without any mutual exclusion. * Mutual exclusion can be ensured by holding cds_wfcq_dequeue_lock(). @@ -190,6 +191,10 @@ ___cds_wfcq_node_sync_next(struct cds_wfcq_node *node) * Content written into the node before enqueue is guaranteed to be * consistent, but no other memory ordering is ensured. * Should be called with cds_wfcq_dequeue_lock() held. + * + * Used by for-like iteration macros in urcu/wfqueue.h: + * __cds_wfcq_for_each_blocking() + * __cds_wfcq_for_each_blocking_safe() */ static inline struct cds_wfcq_node * ___cds_wfcq_first_blocking(struct cds_wfcq_head *head, @@ -211,6 +216,10 @@ ___cds_wfcq_first_blocking(struct cds_wfcq_head *head, * Content written into the node before enqueue is guaranteed to be * consistent, but no other memory ordering is ensured. * Should be called with cds_wfcq_dequeue_lock() held. + * + * Used by for-like iteration macros in urcu/wfqueue.h: + * __cds_wfcq_for_each_blocking() + * __cds_wfcq_for_each_blocking_safe() */ static inline struct cds_wfcq_node * ___cds_wfcq_next_blocking(struct cds_wfcq_head *head, diff --git a/urcu/wfcqueue.h b/urcu/wfcqueue.h index 5576cbf..501120b 100644 --- a/urcu/wfcqueue.h +++ b/urcu/wfcqueue.h @@ -91,8 +91,9 @@ struct cds_wfcq_tail { * * Unless otherwise stated, the caller must ensure mutual exclusion of * queue update operations "dequeue" and "splice" (for source queue). - * Queue read operations "first" and "next" need to be protected against - * concurrent "dequeue" and "splice" (for source queue) by the caller. + * Queue read operations "first" and "next", which are used by + * "for_each" iterations, need to be protected against concurrent + * "dequeue" and "splice" (for source queue) by the caller. * "enqueue", "splice" (for destination queue), and "empty" are the only * operations that can be used without any mutual exclusion. * Mutual exclusion can be ensured by holding cds_wfcq_dequeue_lock(). @@ -202,6 +203,10 @@ extern void __cds_wfcq_splice_blocking( * Content written into the node before enqueue is guaranteed to be * consistent, but no other memory ordering is ensured. * Should be called with cds_wfcq_dequeue_lock() held. + * + * Used by for-like iteration macros: + * __cds_wfcq_for_each_blocking() + * __cds_wfcq_for_each_blocking_safe() */ extern struct cds_wfcq_node *__cds_wfcq_first_blocking( struct cds_wfcq_head *head, @@ -213,6 +218,10 @@ extern struct cds_wfcq_node *__cds_wfcq_first_blocking( * Content written into the node before enqueue is guaranteed to be * consistent, but no other memory ordering is ensured. * Should be called with cds_wfcq_dequeue_lock() held. + * + * Used by for-like iteration macros: + * __cds_wfcq_for_each_blocking() + * __cds_wfcq_for_each_blocking_safe() */ extern struct cds_wfcq_node *__cds_wfcq_next_blocking( struct cds_wfcq_head *head, -- 2.34.1