wfcqueue: document first/next return values

[urcu.git] / urcu / wfstack.h

diff --git a/urcu/wfstack.h b/urcu/wfstack.h
index aa10881506a5ad2609cb62a39b18ee916e1676d2..0e435ba6d8e899ede731739e0fb8cc41db2deaf1 100644 (file)
--- a/urcu/wfstack.h
+++ b/urcu/wfstack.h
@@ -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))