diff options
author | Andy Wingo <wingo@pobox.com> | 2016-11-06 18:11:25 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2016-11-06 18:11:25 +0100 |
commit | 16fe02aa159d6d3e97d82983631c03dcf7af2067 (patch) | |
tree | f3650e50e236f43cf4e07da00fcd36ef1de2f208 /doc/ref/api-scheduling.texi | |
parent | 03ffd726df81731a0b1738bf2bb4842ea730c680 (diff) | |
download | guile-16fe02aa159d6d3e97d82983631c03dcf7af2067.tar.gz |
Update documentation on mutexes
* doc/ref/api-scheduling.texi (Mutexes and Condition Variables):
Update.
Diffstat (limited to 'doc/ref/api-scheduling.texi')
-rw-r--r-- | doc/ref/api-scheduling.texi | 64 |
1 files changed, 19 insertions, 45 deletions
diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi index 9b6e44088..c5015fb63 100644 --- a/doc/ref/api-scheduling.texi +++ b/doc/ref/api-scheduling.texi @@ -466,36 +466,28 @@ function is equivalent to calling @code{make-mutex} with the @code{recursive} kind. @end deffn -@deffn {Scheme Procedure} lock-mutex mutex [timeout [owner]] +@deffn {Scheme Procedure} lock-mutex mutex [timeout] @deffnx {C Function} scm_lock_mutex (mutex) -@deffnx {C Function} scm_lock_mutex_timed (mutex, timeout, owner) -Lock @var{mutex}. If the mutex is already locked, then block and -return only when @var{mutex} has been acquired. +@deffnx {C Function} scm_timed_lock_mutex (mutex, timeout) +Lock @var{mutex} and return @code{#t}. If the mutex is already locked, +then block and return only when @var{mutex} has been acquired. When @var{timeout} is given, it specifies a point in time where the waiting should be aborted. It can be either an integer as returned by @code{current-time} or a pair as returned by @code{gettimeofday}. When the waiting is aborted, @code{#f} is returned. -When @var{owner} is given, it specifies an owner for @var{mutex} other -than the calling thread. @var{owner} may also be @code{#f}, -indicating that the mutex should be locked but left unowned. - -For standard mutexes (@code{make-mutex}), and error is signalled if -the thread has itself already locked @var{mutex}. +For standard mutexes (@code{make-mutex}), an error is signalled if the +thread has itself already locked @var{mutex}. For a recursive mutex (@code{make-recursive-mutex}), if the thread has itself already locked @var{mutex}, then a further @code{lock-mutex} call increments the lock count. An additional @code{unlock-mutex} will be required to finally release. -If @var{mutex} was locked by a thread that exited before unlocking it, -the next attempt to lock @var{mutex} will succeed, but -@code{abandoned-mutex-error} will be signalled. - -When an async (@pxref{Asyncs}) is activated for a thread blocked in -@code{lock-mutex}, the wait is interrupted and the async is executed. -When the async returns, the wait resumes. +When an asynchronous interrupt (@pxref{Asyncs}) is scheduled for a +thread blocked in @code{lock-mutex}, Guile will interrupt the wait, run +the interrupts, and then resume the wait. @end deffn @deftypefn {C Function} void scm_dynwind_lock_mutex (SCM mutex) @@ -505,31 +497,18 @@ context is entered and to be unlocked when it is exited. @deffn {Scheme Procedure} try-mutex mx @deffnx {C Function} scm_try_mutex (mx) -Try to lock @var{mutex} as per @code{lock-mutex}. If @var{mutex} can -be acquired immediately then this is done and the return is @code{#t}. -If @var{mutex} is locked by some other thread then nothing is done and -the return is @code{#f}. +Try to lock @var{mutex} and return @code{#t} if successful, or @code{#f} +otherwise. This is like calling @code{lock-mutex} with an expired +timeout. @end deffn -@deffn {Scheme Procedure} unlock-mutex mutex [condvar [timeout]] +@deffn {Scheme Procedure} unlock-mutex mutex @deffnx {C Function} scm_unlock_mutex (mutex) -@deffnx {C Function} scm_unlock_mutex_timed (mutex, condvar, timeout) -Unlock @var{mutex}. An error is signalled if @var{mutex} is not locked -and was not created with the @code{unchecked-unlock} flag set, or if -@var{mutex} is locked by a thread other than the calling thread and was -not created with the @code{allow-external-unlock} flag set. +Unlock @var{mutex}. An error is signalled if @var{mutex} is not locked. -If @var{condvar} is given, it specifies a condition variable upon -which the calling thread will wait to be signalled before returning. -(This behavior is very similar to that of -@code{wait-condition-variable}, except that the mutex is left in an -unlocked state when the function returns.) - -When @var{timeout} is also given and not false, it specifies a point in -time where the waiting should be aborted. It can be either an integer -as returned by @code{current-time} or a pair as returned by -@code{gettimeofday}. When the waiting is aborted, @code{#f} is -returned. Otherwise the function returns @code{#t}. +``Standard'' and ``recursive'' mutexes can only be unlocked by the +thread that locked them; Guile detects this situation and signals an +error. ``Unowned'' mutexes can be unlocked by any thread. @end deffn @deffn {Scheme Procedure} mutex-owner mutex @@ -593,13 +572,8 @@ Wake up one thread that is waiting for @var{condvar}. Wake up all threads that are waiting for @var{condvar}. @end deffn -@sp 1 -The following are higher level operations on mutexes. These are -available from - -@example -(use-modules (ice-9 threads)) -@end example +Guile also includes some higher-level abstractions for working with +mutexes. @deffn macro with-mutex mutex body1 body2 @dots{} Lock @var{mutex}, evaluate the body @var{body1} @var{body2} @dots{}, |