Document atomic types.

4 files changed, 80 insertions, 3 deletions

diff --git a/doc/ref/general.texi b/doc/ref/general.texi
index 052594c3..0e14ee34 100644
--- a/doc/ref/general.texi
+++ b/doc/ref/general.texi
@@ -26,3 +26,4 @@ of these should be generally useful in any project.
 @include general/util-type.texi
 @include general/lens.texi
 @include general/sxml.texi
+@include general/atomic.texi
diff --git a/doc/ref/general/atomic.texi b/doc/ref/general/atomic.texi
new file mode 100644
index 00000000..52218944
--- /dev/null
+++ b/doc/ref/general/atomic.texi
@@ -0,0 +1,74 @@
+@node Atomic Operations and Datastructures
+@section Atomic Operations and Datastructures
+
+@code{(hnh util atomic)}
+
+@defmac with-mutex mutex body ...
+Equivalent to Guile's @code{with-mutex} from
+@code{(ice-9 threads)}.
+Re-implemented to be able to drop an ice-9 dependency@c
+@footnote{As if Scheme will ever be portable enough for that to matter}.
+@end defmac
+
+A few ``atomic'' data structures are also available. These allow
+synchronized insertion and removal from the set.
+
+@node Atomic Queue
+@subsection Atomic Queue
+
+@code{(hnh util atomic-queue)}
+
+@defun atomic-queue
+Create a new atomic queue. Each queue will internally syncronize all
+modifications of state. Sepparate queue's don't affect each other.
+@end defun
+
+@defun atomic-queue? x
+Check if @var{x} is an atomic queue?
+@end defun
+
+@defun enqueue! value queue
+Add @var{value} to the back of @var{queue}.
+@end defun
+
+@defun queue-peek queue
+Returns the first element of @var{queue}, or raises an exception if
+the queue is empty.
+@end defun
+
+@defun dequeue! queue
+remove and retrun the first element of @var{queue}, or @code{#f} if the queue is
+empty.
+@end defun
+
+@defun queue->list queue
+Extract contents of @var{queue}. With the front of the list in the car
+slot, and subsequent elements following.
+@end defun
+
+@node Atomic Stack
+@subsection Atomic Stack
+
+@code{(hnh util atomic-stack)}
+
+@defun atomic-stack
+Creates a new atomic stack. See @code{atomic-queue} further details.
+@end defun
+
+@defun atomic-stack? x
+Check if @var{x} is an atomic stack.
+@end defun
+
+@defun push! value stack
+@end defun
+
+@defun stack-peek stack
+@end defun
+
+@defun pop! value stack
+@end defun
+
+@defun stack->list stack
+Extract the contents of @var{stack}. The topmost element will be first
+in the returned list.
+@end defun
diff --git a/module/hnh/util/atomic-stack.scm b/module/hnh/util/atomic-stack.scm
index 6b17724d..4e8ed871 100644
--- a/module/hnh/util/atomic-stack.scm
+++ b/module/hnh/util/atomic-stack.scm
@@ -19,9 +19,6 @@
 (define (atomic-stack)
   (%atomic-stack '() (make-mutex)))
 
-(define (stack->list stack)
-  (stack-contents stack))
-
 (define (push! value stack)
   (typecheck stack atomic-stack?)
   (with-mutex (stack-mutex stack)
@@ -41,3 +38,5 @@
               (stack-contents-set!
                stack (cdr (stack-contents stack)))))))
 
+(define (stack->list stack)
+  (stack-contents stack))
diff --git a/tests/unit/util/atomic-queue.scm b/tests/unit/util/atomic-queue.scm
index 428f4457..07ec0329 100644
--- a/tests/unit/util/atomic-queue.scm
+++ b/tests/unit/util/atomic-queue.scm
@@ -15,6 +15,9 @@
 
 (enqueue! 4 q)
 
+(test-equal "Returned order when extracting list"
+  '(2 3 4) (queue->list q))
+
 (test-equal 2 (dequeue! q))
 (test-equal 3 (dequeue! q))
 (test-equal 4 (dequeue! q))