[PATCH] Update documentation for libthread.
[Thread Prev] | [Thread Next]
- Subject: [PATCH] Update documentation for libthread.
- From: iriri <iri@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx>
- Reply-to: myrddin-dev@xxxxxxxxxxxxxx
- Date: Thu, 26 Jul 2018 23:46:52 -0700
- To: "myrddin-dev" <myrddin-dev@xxxxxxxxxxxxxx>
--- 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
Re: [PATCH] Update documentation for libthread. | Ori Bernstein <ori@xxxxxxxxxxxxxx> |
- Prev by Date: [PATCH] Fix typo in plan 9 mksem.
- Next by Date: Re: [PATCH] Update documentation for libthread.
- Previous by thread: [PATCH] Fix typo in plan 9 mksem.
- Next by thread: Re: [PATCH] Update documentation for libthread.
- Index(es):