(Arbiters): Tweak wording for clarity, note any

thread can unlock not just the one which locked.

diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi
index c5e6520..c3aef48 100644 (file)
--- a/doc/ref/api-scheduling.texi
+++ b/doc/ref/api-scheduling.texi
@@ -25,36 +25,36 @@ reviewed and largely reorganized.]
 
 @node Arbiters
 @subsection Arbiters
-
 @cindex arbiters
 
-@c FIXME::martin: Review me!
+Arbiters are synchronization objects, they can be used by threads to
+control access to a shared resource.  An arbiter can be locked to
+indicate a resource is in use, and unlocked when done.
 
-Arbiters are synchronization objects.  They are created with
-@code{make-arbiter}.  Two or more threads can synchronize on an arbiter
-by trying to lock it using @code{try-arbiter}.  This call will succeed
-if no other thread has called @code{try-arbiter} on the arbiter yet,
-otherwise it will fail and return @code{#f}.  Once an arbiter is
-successfully locked, it cannot be locked by another thread until the
-thread holding the arbiter calls @code{release-arbiter} to unlock it.
+An arbiter is like a light-weight mutex (@pxref{Low level thread
+primitives}).  It uses less memory and may be a little faster, but
+there's no way for a thread to block waiting on an arbiter, it can
+only test and get the status returned.
 
 @deffn {Scheme Procedure} make-arbiter name
 @deffnx {C Function} scm_make_arbiter (name)
-Return an object of type arbiter and name @var{name}. Its
-state is initially unlocked.  Arbiters are a way to achieve
-process synchronization.
+Return an arbiter object, initially unlocked.  Currently @var{name} is
+only used for diagnostic output.
 @end deffn
 
 @deffn {Scheme Procedure} try-arbiter arb
 @deffnx {C Function} scm_try_arbiter (arb)
-Return @code{#t} and lock the arbiter @var{arb} if the arbiter
-was unlocked. Otherwise, return @code{#f}.
+If @var{arb} is unlocked, then lock it and return @code{#t}.  If
+@var{arb} is already locked, then do nothing and return @code{#f}.
 @end deffn
 
 @deffn {Scheme Procedure} release-arbiter arb
 @deffnx {C Function} scm_release_arbiter (arb)
-Return @code{#t} and unlock the arbiter @var{arb} if the
-arbiter was locked. Otherwise, return @code{#f}.
+If @var{arb} is locked, then unlock it and return @code{#t}.  If
+@var{arb} is already unlocked, then do nothing and return @code{#f}.
+
+Typical usage is for the thread which locked an arbiter to later
+release it, but that's not required, any thread can release it.
 @end deffn