X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=urcu%2Fwfstack.h;h=0e435ba6d8e899ede731739e0fb8cc41db2deaf1;hb=131a29a6627c8a1aee35491ac43984ebe756909c;hp=b6992e888cfa71f2334c485034c11f7a788b9fac;hpb=edac6b69ad8b690437c4624cebb7eef465a09a7e;p=urcu.git

diff --git a/urcu/wfstack.h b/urcu/wfstack.h
index b6992e8..0e435ba 100644
--- a/urcu/wfstack.h
+++ b/urcu/wfstack.h
@@ -6,7 +6,7 @@
  *
  * Userspace RCU library - Stack with wait-free push, blocking traversal.
  *
- * Copyright 2010 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+ * Copyright 2010-2012 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -38,9 +38,10 @@ extern "C" {
  * Stack implementing push, pop, pop_all operations, as well as iterator
  * on the stack head returned by pop_all.
  *
- * Wait-free operations: cds_wfs_push, __cds_wfs_pop_all.
- * Blocking operations: cds_wfs_pop, cds_wfs_pop_all, iteration on stack
- *                      head returned by pop_all.
+ * Wait-free operations: cds_wfs_push, __cds_wfs_pop_all, cds_wfs_empty,
+ *                       cds_wfs_first.
+ * Blocking operations: cds_wfs_pop, cds_wfs_pop_all, cds_wfs_next,
+ *                      iteration on stack head returned by pop_all.
  *
  * Synchronization table:
  *
@@ -98,7 +99,7 @@ struct cds_wfs_stack {
  * For iteration on cds_wfs_head returned by __cds_wfs_pop_all or
  * cds_wfs_pop_all_blocking.
  */
-#define cds_wfs_first_blocking		_cds_wfs_first_blocking
+#define cds_wfs_first			_cds_wfs_first
 #define cds_wfs_next_blocking		_cds_wfs_next_blocking
 
 /* Pop locking with internal mutex */
@@ -154,7 +155,7 @@ extern struct cds_wfs_node *cds_wfs_pop_blocking(struct cds_wfs_stack *s);
 extern struct cds_wfs_head *cds_wfs_pop_all_blocking(struct cds_wfs_stack *s);
 
 /*
- * cds_wfs_first_blocking: get first node of a popped stack.
+ * cds_wfs_first: get first node of a popped stack.
  *
  * Content written into the node before enqueue is guaranteed to be
  * consistent, but no other memory ordering is ensured.
@@ -162,8 +163,10 @@ extern struct cds_wfs_head *cds_wfs_pop_all_blocking(struct cds_wfs_stack *s);
  * Used by for-like iteration macros in urcu/wfstack.h:
  * cds_wfs_for_each_blocking()
  * cds_wfs_for_each_blocking_safe()
+ *
+ * Returns NULL if popped stack is empty, top stack node otherwise.
  */
-extern struct cds_wfs_node *cds_wfs_first_blocking(struct cds_wfs_head *head);
+extern struct cds_wfs_node *cds_wfs_first(struct cds_wfs_head *head);
 
 /*
  * cds_wfs_next_blocking: get next node of a popped stack.
@@ -174,6 +177,9 @@ extern struct cds_wfs_node *cds_wfs_first_blocking(struct cds_wfs_head *head);
  * Used by for-like iteration macros in urcu/wfstack.h:
  * cds_wfs_for_each_blocking()
  * cds_wfs_for_each_blocking_safe()
+ *
+ * Returns NULL if reached end of popped stack, non-NULL next stack
+ * node otherwise.
  */
 extern struct cds_wfs_node *cds_wfs_next_blocking(struct cds_wfs_node *node);
 
@@ -240,7 +246,7 @@ extern struct cds_wfs_head *__cds_wfs_pop_all(struct cds_wfs_stack *s);
  * consistent, but no other memory ordering is ensured.
  */
 #define cds_wfs_for_each_blocking(head, node)			\
-	for (node = cds_wfs_first_blocking(head);		\
+	for (node = cds_wfs_first(head);			\
 		node != NULL;					\
 		node = cds_wfs_next_blocking(node))
 
@@ -256,7 +262,7 @@ extern struct cds_wfs_head *__cds_wfs_pop_all(struct cds_wfs_stack *s);
  * consistent, but no other memory ordering is ensured.
  */
 #define cds_wfs_for_each_blocking_safe(head, node, n)			   \
-	for (node = cds_wfs_first_blocking(head),			   \
+	for (node = cds_wfs_first(head),				   \
 			n = (node ? cds_wfs_next_blocking(node) : NULL);   \
 		node != NULL;						   \
 		node = n, n = (node ? cds_wfs_next_blocking(node) : NULL))