From: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Date: Wed, 5 Dec 2012 13:53:08 +0000 (-0500)
Subject: wfstack: document first/next return values
X-Git-Tag: v0.8.0~133
X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=8af2956c86ba7556b0f7de3ad999a6b29ffbab9a;p=urcu.git

wfstack: document first/next return values

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

diff --git a/urcu/static/wfstack.h b/urcu/static/wfstack.h
index 24f6cb4..1a0e4d7 100644
--- a/urcu/static/wfstack.h
+++ b/urcu/static/wfstack.h
@@ -291,6 +291,8 @@ _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.
  */
 static inline struct cds_wfs_node *
 _cds_wfs_first_blocking(struct cds_wfs_head *head)
@@ -309,6 +311,9 @@ _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.
  */
 static inline struct cds_wfs_node *
 _cds_wfs_next_blocking(struct cds_wfs_node *node)
diff --git a/urcu/wfstack.h b/urcu/wfstack.h
index aa10881..20d1882 100644
--- a/urcu/wfstack.h
+++ b/urcu/wfstack.h
@@ -162,6 +162,8 @@ 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);
 
@@ -174,6 +176,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);