From: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Date: Sat, 26 Jan 2013 15:51:48 +0000 (-0500)
Subject: doc/cds-api.txt: expand documentation
X-Git-Tag: v0.8.0~113
X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=e43447f92694eaaaf877799d4ecaa84a56bb8cda;p=urcu.git

doc/cds-api.txt: expand documentation

Expand explanations, reorder items to have all wait-free descriptions
first, so that the rculfqueue API comes last, since it is less
featureful and is the only API of the queues/stacks to actually rely on
RCU.

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

diff --git a/doc/cds-api.txt b/doc/cds-api.txt
index 81d511c..8896e20 100644
--- a/doc/cds-api.txt
+++ b/doc/cds-api.txt
@@ -28,28 +28,36 @@ urcu/rcuhlist.h:
 	for implementing hash tables. Downside over rculist.h: lookup of
 	tail in O(n).
 
-urcu/rculfqueue.h:
+urcu/wfstack.h:
 
-	RCU queue with lock-free enqueue, lock-free dequeue. RCU used to
-	provide existance guarantees.
+	Stack with wait-free push and wait-free pop_all. Both blocking
+	and non-blocking pop and traversal operations are provided.
+	This stack does _not_ specifically rely on RCU.
+	Various synchronization techniques can be used to deal with
+	pop ABA. Those are detailed in the API.
 
 urcu/wfcqueue.h:
 
-	Concurrent queue with wait-free enqueue, blocking traversal.
-	This queue does _not_ use RCU.
+	Concurrent queue with wait-free enqueue. Both blocking and
+	non-blocking dequeue, splice (move all elements from one queue
+	to another), and traversal operations are provided.
+	This queue does _not_ specifically rely on RCU. Mutual exclusion
+	is used to protect dequeue, splice (from source queue) and
+	traversal (see API for details).
 	(note: deprecates urcu/wfqueue.h)
 
 urcu/lfstack.h:
 
-	RCU stack with lock-free push, lock-free dequeue. Various
-	synchronization techniques can be used to deal with "pop" ABA.
-	Those are detailed in the API.
+	Stack with lock-free push, lock-free pop, wait-free pop_all,
+	wait-free traversal. Various synchronization techniques can be
+	used to deal with pop ABA. Those are detailed in the API.
+	This stack does _not_ specifically rely on RCU.
 	(note: deprecates urcu/rculfstack.h)
 
-urcu/wfstack.h:
+urcu/rculfqueue.h:
 
-	Stack with wait-free enqueue, blocking dequeue. This stack does
-	_not_ use RCU.
+	RCU queue with lock-free enqueue, lock-free dequeue.
+	This queue relies on RCU for existence guarantees.
 
 urcu/rculfhash.h: