From 3941006bf022a066499390d7f7aff99fea64aa50 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Sun, 8 Oct 2023 11:45:32 +0200
Subject: Document atomic types.

---
 doc/ref/general.texi             |  1 +
 doc/ref/general/atomic.texi      | 74 ++++++++++++++++++++++++++++++++++++++++
 module/hnh/util/atomic-stack.scm |  5 ++-
 tests/unit/util/atomic-queue.scm |  3 ++
 4 files changed, 80 insertions(+), 3 deletions(-)
 create mode 100644 doc/ref/general/atomic.texi

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))
-- 
cgit v1.2.3