From e136aab0cc2fa75367f59b173d438e2ec006e10a Mon Sep 17 00:00:00 2001 From: Kevin Ryde Date: Thu, 5 Aug 2004 00:38:13 +0000 Subject: [PATCH] (Arbiters): Tweak wording for clarity, note any thread can unlock not just the one which locked. --- doc/ref/api-scheduling.texi | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi index c5e652030..c3aef48a0 100644 --- 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