X-Git-Url: https://git.liburcu.org/?p=urcu.git;a=blobdiff_plain;f=urcu%2Flfstack.h;h=5a9bca368775db300cbd1bac44e5fbcd51c6ce47;hp=cd8e958dfc2ac6e0151b4f73685cd615dac74ded;hb=200d100e05ed8e10c47f971939042f2406df92ef;hpb=817a017859ab974276438fbebee50e07aeb6f346

diff --git a/urcu/lfstack.h b/urcu/lfstack.h
index cd8e958..5a9bca3 100644
--- a/urcu/lfstack.h
+++ b/urcu/lfstack.h
@@ -84,10 +84,10 @@ struct cds_lfs_stack {
  * struct cds_lfs_stack and struct __cds_lfs_stack on any of those two
  * types.
  */
-typedef union __attribute__((__transparent_union__)) {
+typedef union {
 	struct __cds_lfs_stack *_s;
 	struct cds_lfs_stack *s;
-} cds_lfs_stack_ptr_t;
+} __attribute__((__transparent_union__)) cds_lfs_stack_ptr_t;
 
 #ifdef _LGPL_SOURCE
 
@@ -95,6 +95,7 @@ typedef union __attribute__((__transparent_union__)) {
 
 #define cds_lfs_node_init		_cds_lfs_node_init
 #define cds_lfs_init			_cds_lfs_init
+#define cds_lfs_destroy			_cds_lfs_destroy
 #define __cds_lfs_init			___cds_lfs_init
 #define cds_lfs_empty			_cds_lfs_empty
 #define cds_lfs_push			_cds_lfs_push
@@ -119,12 +120,20 @@ typedef union __attribute__((__transparent_union__)) {
 extern void cds_lfs_node_init(struct cds_lfs_node *node);
 
 /*
- * cds_lfs_init: initialize lock-free stack.
+ * cds_lfs_init: initialize lock-free stack (with locking). Pair with
+ * cds_lfs_destroy().
  */
 extern void cds_lfs_init(struct cds_lfs_stack *s);
 
 /*
- * __cds_lfs_init: initialize lock-free stack.
+ * cds_lfs_destroy: destroy lock-free stack (with lock). Pair with
+ * cds_lfs_init().
+ */
+extern void cds_lfs_destroy(struct cds_lfs_stack *s);
+
+/*
+ * __cds_lfs_init: initialize lock-free stack (without lock).
+ * Don't pair with any destroy function.
  */
 extern void __cds_lfs_init(struct __cds_lfs_stack *s);
 
@@ -178,9 +187,12 @@ extern void cds_lfs_pop_unlock(struct cds_lfs_stack *s);
  * __cds_lfs_pop needs to be synchronized using one of the following
  * techniques:
  *
- * 1) Calling __cds_lfs_pop under rcu read lock critical section. The
- *    caller must wait for a grace period to pass before freeing the
- *    returned node or modifying the cds_lfs_node structure.
+ * 1) Calling __cds_lfs_pop under rcu read lock critical section.
+ *    Both __cds_lfs_pop and __cds_lfs_pop_all callers must wait for a
+ *    grace period to pass before freeing the returned node or pushing
+ *    the node back into the stack. It is valid to overwrite the content
+ *    of cds_lfs_node immediately after __cds_lfs_pop and
+ *    __cds_lfs_pop_all.
  * 2) Using mutual exclusion (e.g. mutexes) to protect __cds_lfs_pop
  *    and __cds_lfs_pop_all callers.
  * 3) Ensuring that only ONE thread can call __cds_lfs_pop() and
@@ -196,10 +208,12 @@ extern struct cds_lfs_node *__cds_lfs_pop(cds_lfs_stack_ptr_t s);
  * matching the technique used to synchronize __cds_lfs_pop:
  *
  * 1) If __cds_lfs_pop is called under rcu read lock critical section,
- *    both __cds_lfs_pop and cds_lfs_pop_all callers must wait for a
- *    grace period to pass before freeing the returned node or modifying
- *    the cds_lfs_node structure. However, no RCU read-side critical
- *    section is needed around __cds_lfs_pop_all.
+ *    both __cds_lfs_pop and __cds_lfs_pop_all callers must wait for a
+ *    grace period to pass before freeing the returned node or pushing
+ *    the node back into the stack. It is valid to overwrite the content
+ *    of cds_lfs_node immediately after __cds_lfs_pop and
+ *    __cds_lfs_pop_all. No RCU read-side critical section is needed
+ *    around __cds_lfs_pop_all.
  * 2) Using mutual exclusion (e.g. mutexes) to protect __cds_lfs_pop and
  *    __cds_lfs_pop_all callers.
  * 3) Ensuring that only ONE thread can call __cds_lfs_pop() and