[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 22/24: Update documentation on mutexes
From: |
Andy Wingo |
Subject: |
[Guile-commits] 22/24: Update documentation on mutexes |
Date: |
Sun, 6 Nov 2016 18:00:46 +0000 (UTC) |
wingo pushed a commit to branch master
in repository guile.
commit 16fe02aa159d6d3e97d82983631c03dcf7af2067
Author: Andy Wingo <address@hidden>
Date: Sun Nov 6 18:11:25 2016 +0100
Update documentation on mutexes
* doc/ref/api-scheduling.texi (Mutexes and Condition Variables):
Update.
---
doc/ref/api-scheduling.texi | 64 +++++++++++++------------------------------
1 file changed, 19 insertions(+), 45 deletions(-)
diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi
index 9b6e440..c5015fb 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
address@hidden {Scheme Procedure} lock-mutex mutex [timeout [owner]]
address@hidden {Scheme Procedure} lock-mutex mutex [timeout]
@deffnx {C Function} scm_lock_mutex (mutex)
address@hidden {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.
address@hidden {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
address@hidden will be signalled.
-
-When an async (@pxref{Asyncs}) is activated for a thread blocked in
address@hidden, 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
address@hidden {Scheme Procedure} unlock-mutex mutex [condvar [timeout]]
address@hidden {Scheme Procedure} unlock-mutex mutex
@deffnx {C Function} scm_unlock_mutex (mutex)
address@hidden {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
address@hidden 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
address@hidden, 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
address@hidden 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
address@hidden 1
-The following are higher level operations on mutexes. These are
-available from
-
address@hidden
-(use-modules (ice-9 threads))
address@hidden 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{},
- [Guile-commits] 07/24: SRFI-18 threads disjoint from guile threads, (continued)
- [Guile-commits] 07/24: SRFI-18 threads disjoint from guile threads, Andy Wingo, 2016/11/06
- [Guile-commits] 21/24: scm_timed_lock_mutex replaces scm_lock_mutex_timed, Andy Wingo, 2016/11/06
- [Guile-commits] 15/24: Recursively locking a SRFI-18 mutex blocks, Andy Wingo, 2016/11/06
- [Guile-commits] 19/24: Separate fat mutex unlock and wait operations, Andy Wingo, 2016/11/06
- [Guile-commits] 06/24: Update SRFI-18 documentation., Andy Wingo, 2016/11/06
- [Guile-commits] 11/24: Remove thread held pthread_mutex field, Andy Wingo, 2016/11/06
- [Guile-commits] 13/24: Move more functionality to SRFI-18 mutex-unlock!, Andy Wingo, 2016/11/06
- [Guile-commits] 03/24: SRFI-18 mutexes disjoint from Guile mutexes, Andy Wingo, 2016/11/06
- [Guile-commits] 16/24: Remove unchecked-unlock facility from Guile mutexes, Andy Wingo, 2016/11/06
- [Guile-commits] 24/24: Update NEWS., Andy Wingo, 2016/11/06
- [Guile-commits] 22/24: Update documentation on mutexes,
Andy Wingo <=
- [Guile-commits] 20/24: Update mutex documentation, Andy Wingo, 2016/11/06
- [Guile-commits] 17/24: Replace scm_make_mutex_with_flags, Andy Wingo, 2016/11/06
- [Guile-commits] 23/24: Minor editing in api-scheduling.texi, Andy Wingo, 2016/11/06