Eigenstate: myrddin-dev mailing list

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH] Update documentation for libthread.



---
 doc/libthread/index.txt | 103 ++++++++++++++++++++++++++++++++++------
 1 file changed, 89 insertions(+), 14 deletions(-)

diff --git a/doc/libthread/index.txt b/doc/libthread/index.txt
index dd26296..8846168 100644
--- a/doc/libthread/index.txt
+++ b/doc/libthread/index.txt
@@ -19,13 +19,21 @@ Summary
 			xchg	: (p : @a#, new : @a -> @a)
 		;;
 
+		type mutex = struct
+			...
+		;;
+
+		type sem = struct
+			...
+		;;
+
 		type cond = struct
 			...
 		;;
 
-		type mutex = struct
+		type waitgrp = struct
 			...
-		;;	
+		;;
 
 		impl atomic int32
 		impl atomic int64
@@ -41,17 +49,28 @@ Summary
 		const mtxtrylock	: (mtx : mutex# -> bool)
 		const mtxunlock	: (mtx : mutex# -> void)
 
+		/* semaphores */
+		const mksem : (v : uint32 -> sem)
+		const semwait : (s : sem# -> void)
+		const semtrywait : (s : sem# -> bool)
+		const sempost : (s : sem# -> void)
+
 		/* condition variables */
 		const mkcond	: (mtx : mutex# -> cond)
 		const condwait	: (cond : cond# -> void)
 		const condsignal	: (cond : cond# -> void)
 		const condbroadcast	: (cond : cond# -> void)
 
-		/* semaphores */
-		const mksem : (v : uint32 -> sem)
-		const semwait : (s : sem# -> void)
-		const semtrywait : (s : sem# -> bool)
-		const sempost : (s : sem# -> void)
+		/* wait groups */
+		const mkwg : (v : uint32 -> waitgrp)
+		const wgwait : (w : waitgrp# -> void)
+		const wgpost : (w : waitgrp# -> void)
+
+		/* atomic pointer operations */
+		generic xgetptr : (p : @a## -> std.option(@a#))
+		generic xsetptr : (p : @a##, v : std.option(@a#) -> void)
+		generic xcasptr : (p : @a##, old : std.option(@a#), new : std.option(@a#) -> std.option(@a#))
+		generic xchgptr : (p : @a##, new : std.option(@a#) -> std.option(@a#))
 
 		/* misc */
 		const ncpu	: (-> int)
@@ -59,11 +78,12 @@ Summary
 
 Types
 -----
+	type tid
 
-	type cond = struct ... ;;
 	type mutex = struct ... ;;
 	type sem = struct ... ;;
-
+	type cond = struct ... ;;
+	type waitgrp = struct ... ;;
 
 	trait atomic @a::(integral,numeric) =
 	        xget	: (p : @a# -> @a)
@@ -74,6 +94,33 @@ Types
 	        xchg	: (p : @a#, new : @a -> @a)
 	;;
 
+Impls
+-----
+
+The `atomic` trait is implemented for the types `int32`, `int64`, `uint32`, and
+`uint64`.
+
+	xget	: (p : @a# -> @a)
+
+Atomically gets the value at address `p`.
+
+	xset	: (p : @a#, v : @a -> void)
+
+Atomically sets the value at address `p` to `v`.
+
+	xadd	: (p : @a#, v : @a -> @a)
+
+Atomically adds `v` to the value at address `p` and returns the previous value.
+
+	xcas	: (p : @a#, old : @a, new : @a -> @a)
+
+Atomically compares the value at address `p` to `old` and, if they are equal,
+swaps that value with `new`. Returns `old` if the swap succeeds, or the actual
+value at address `p` if it does not.
+
+	xchg	: (p : @a#, new : @a -> @a)
+
+Atomically exchanges the value at address `p` with `new`.
 
 Thread Creation
 ---------------
@@ -100,8 +147,8 @@ Locks a mutex. Blocks if the mutex is already locked.
 
 	const mtxtrylock	: (mtx : mutex# -> bool)
 
-Attempts to lock a mutex. Returns true if the lock was
-taken successful. Returns false if the lock was not taken.
+Attempts to lock a mutex. Returns true if the lock was taken successfully.
+Returns false if the lock was not taken.
 
 This call does not block.
 
@@ -141,19 +188,47 @@ variable.
 
 	const condwait	: (cond : cond# -> void)
 
-Waits on the condition to be notiifed on. Must be called with the associated
+Waits on the condition to be notified on. Must be called with the associated
 mutex locked. Unlocks the mutex that is associated with the condition variable
 and sleeps until someone has notified on the condition variable.
 
 	const condsignal	: (cond : cond# -> void)
 
-Wakes at least one waiter on the condition variable, allowing them to take the
-mutex.
+Wakes one waiter on the condition variable, allowing them to take the mutex.
 
 	const condbroadcast	: (cond : cond# -> void)
 
 Wakes all waiters on the condition variable.
 
+Wait Groups
+-----------
+
+	const mkwg : (v : uint32 -> waitgrp)
+
+Creates a wait group with the initial value `v`.
+
+	const wgwait : (w : waitgrp# -> void)
+
+Blocks if the value of the wait group is nonzero.
+
+	const wgpost : (w : waitgrp# -> void)
+
+Decrements the value of the wait group. If the new value is zero, all threads
+waiting on the wait group are woken.
+
+Posting to a wait group that is already at zero is an error.
+
+Atomic Pointer Operations
+-------------------------
+
+	generic xgetptr : (p : @a## -> std.option(@a#))
+	generic xsetptr : (p : @a##, v : std.option(@a#) -> void)
+	generic xcasptr : (p : @a##, old : std.option(@a#), new : std.option(@a#) -> std.option(@a#))
+	generic xchgptr : (p : @a##, new : std.option(@a#) -> std.option(@a#))
+
+These are identical to the corresponding atomic implementations for integral
+types except `std.Some v` is used to represent a nonzero pointer and `std.None`
+is used to represent the zero pointer.
 
 Misc
 ----
-- 
2.18.0


Follow-Ups:
Re: [PATCH] Update documentation for libthread.Ori Bernstein <ori@xxxxxxxxxxxxxx>