From: mathieu.desnoyers@efficios.com (Mathieu Desnoyers)
Subject: [lttng-dev] [urcu commit] wfcqueue: clarify locking usage
Date: Fri, 12 Oct 2012 10:35:39 -0400 [thread overview]
Message-ID: <20121012143539.GA17214@Krystal> (raw)
commit 1fe734e1914993dfa395e2b81e5c9ee0115cc56c
Author: Mathieu Desnoyers <mathieu.desnoyers at efficios.com>
Date: Fri Oct 12 10:33:20 2012 -0400
wfcqueue: clarify locking usage
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers at efficios.com>
diff --git a/urcu/static/wfcqueue.h b/urcu/static/wfcqueue.h
index 2c8c447..2ca9eeb 100644
--- a/urcu/static/wfcqueue.h
+++ b/urcu/static/wfcqueue.h
@@ -59,6 +59,10 @@ extern "C" {
*
* For convenience, cds_wfcq_dequeue_blocking() and
* cds_wfcq_splice_blocking() hold the dequeue lock.
+ *
+ * Besides locking, mutual exclusion of dequeue, splice and iteration
+ * can be ensured by performing all of those operations from a single
+ * thread, without requiring any lock.
*/
#define WFCQ_ADAPT_ATTEMPTS 10 /* Retry if being set */
@@ -192,7 +196,8 @@ ___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.
+ * Dequeue/splice/iteration mutual exclusion should be ensured by the
+ * caller.
*
* Used by for-like iteration macros in urcu/wfqueue.h:
* __cds_wfcq_for_each_blocking()
@@ -217,7 +222,8 @@ ___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.
+ * Dequeue/splice/iteration mutual exclusion should be ensured by the
+ * caller.
*
* Used by for-like iteration macros in urcu/wfqueue.h:
* __cds_wfcq_for_each_blocking()
@@ -259,7 +265,8 @@ ___cds_wfcq_next_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.
* It is valid to reuse and free a dequeued node immediately.
- * Should be called with cds_wfcq_dequeue_lock() held.
+ * Dequeue/splice/iteration mutual exclusion should be ensured by the
+ * caller.
*/
static inline struct cds_wfcq_node *
___cds_wfcq_dequeue_blocking(struct cds_wfcq_head *head,
@@ -308,7 +315,8 @@ ___cds_wfcq_dequeue_blocking(struct cds_wfcq_head *head,
*
* Dequeue all nodes from src_q.
* dest_q must be already initialized.
- * Should be called with cds_wfcq_dequeue_lock() held on src_q.
+ * Dequeue/splice/iteration mutual exclusion for src_q should be ensured
+ * by the caller.
*/
static inline void
___cds_wfcq_splice_blocking(
@@ -345,7 +353,7 @@ ___cds_wfcq_splice_blocking(
*
* Content written into the node before enqueue is guaranteed to be
* consistent, but no other memory ordering is ensured.
- * Mutual exlusion with (and only with) cds_wfcq_splice_blocking is
+ * Mutual exlusion with cds_wfcq_splice_blocking and dequeue lock is
* ensured.
* It is valid to reuse and free a dequeued node immediately.
*/
@@ -368,7 +376,7 @@ _cds_wfcq_dequeue_blocking(struct cds_wfcq_head *head,
* dest_q must be already initialized.
* Content written into the node before enqueue is guaranteed to be
* consistent, but no other memory ordering is ensured.
- * Mutual exlusion with (and only with) cds_wfcq_dequeue_blocking is
+ * Mutual exlusion with cds_wfcq_dequeue_blocking and dequeue lock is
* ensured.
*/
static inline void
diff --git a/urcu/wfcqueue.h b/urcu/wfcqueue.h
index b13aa7b..ba2f2ed 100644
--- a/urcu/wfcqueue.h
+++ b/urcu/wfcqueue.h
@@ -102,6 +102,10 @@ struct cds_wfcq_tail {
*
* For convenience, cds_wfcq_dequeue_blocking() and
* cds_wfcq_splice_blocking() hold the dequeue lock.
+ *
+ * Besides locking, mutual exclusion of dequeue, splice and iteration
+ * can be ensured by performing all of those operations from a single
+ * thread, without requiring any lock.
*/
/*
@@ -151,7 +155,8 @@ extern void cds_wfcq_enqueue(struct cds_wfcq_head *head,
* Content written into the node before enqueue is guaranteed to be
* consistent, but no other memory ordering is ensured.
* It is valid to reuse and free a dequeued node immediately.
- * Mutual exlusion with dequeuers is ensured internally.
+ * Mutual exlusion with cds_wfcq_dequeue_blocking and dequeue lock is
+ * ensured.
*/
extern struct cds_wfcq_node *cds_wfcq_dequeue_blocking(
struct cds_wfcq_head *head,
@@ -164,7 +169,8 @@ extern struct cds_wfcq_node *cds_wfcq_dequeue_blocking(
* dest_q must be already initialized.
* Content written into the node before enqueue is guaranteed to be
* consistent, but no other memory ordering is ensured.
- * Mutual exlusion with dequeuers is ensured internally.
+ * Mutual exlusion with cds_wfcq_dequeue_blocking and dequeue lock is
+ * ensured.
*/
extern void cds_wfcq_splice_blocking(
struct cds_wfcq_head *dest_q_head,
@@ -178,7 +184,8 @@ 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.
* It is valid to reuse and free a dequeued node immediately.
- * Should be called with cds_wfcq_dequeue_lock() held.
+ * Dequeue/splice/iteration mutual exclusion should be ensured by the
+ * caller.
*/
extern struct cds_wfcq_node *__cds_wfcq_dequeue_blocking(
struct cds_wfcq_head *head,
@@ -191,7 +198,8 @@ extern struct cds_wfcq_node *__cds_wfcq_dequeue_blocking(
* dest_q must be already initialized.
* 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.
+ * Dequeue/splice/iteration mutual exclusion for src_q should be ensured
+ * by the caller.
*/
extern void __cds_wfcq_splice_blocking(
struct cds_wfcq_head *dest_q_head,
@@ -204,7 +212,8 @@ 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.
+ * Dequeue/splice/iteration mutual exclusion should be ensured by the
+ * caller.
*
* Used by for-like iteration macros:
* __cds_wfcq_for_each_blocking()
@@ -219,7 +228,8 @@ 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.
+ * Dequeue/splice/iteration mutual exclusion should be ensured by the
+ * caller.
*
* Used by for-like iteration macros:
* __cds_wfcq_for_each_blocking()
@@ -241,7 +251,8 @@ extern struct cds_wfcq_node *__cds_wfcq_next_blocking(
*
* Content written into each node before enqueue is guaranteed to be
* consistent, but no other memory ordering is ensured.
- * Should be called with cds_wfcq_dequeue_lock() held.
+ * Dequeue/splice/iteration mutual exclusion should be ensured by the
+ * caller.
*/
#define __cds_wfcq_for_each_blocking(head, tail, node) \
for (node = __cds_wfcq_first_blocking(head, tail); \
@@ -259,7 +270,8 @@ extern struct cds_wfcq_node *__cds_wfcq_next_blocking(
*
* Content written into each node before enqueue is guaranteed to be
* consistent, but no other memory ordering is ensured.
- * Should be called with cds_wfcq_dequeue_lock() held.
+ * Dequeue/splice/iteration mutual exclusion should be ensured by the
+ * caller.
*/
#define __cds_wfcq_for_each_blocking_safe(head, tail, node, n) \
for (node = __cds_wfcq_first_blocking(head, tail), \
--
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com
reply other threads:[~2012-10-12 14:35 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20121012143539.GA17214@Krystal \
--to=mathieu.desnoyers@efficios.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox