diff --git a/src/doc/manual/extensions/mp_ref_cv.txi b/src/doc/manual/extensions/mp_ref_cv.txi index 659c8e0e4..0618e688f 100644 --- a/src/doc/manual/extensions/mp_ref_cv.txi +++ b/src/doc/manual/extensions/mp_ref_cv.txi @@ -26,9 +26,23 @@ Creates a condition variable. @end deftypefun @defun mp:condition-variable-wait cv lock -Release @var{lock} and suspend thread until condition -@coderef{mp:condition-variable-signal} is called on @var{cv}. When thread -resumes re-aquire @var{lock}. +Release @var{lock} and suspend thread until +@coderef{mp:condition-variable-signal} or +@coderef{mp:condition-variable-broadcast} is called on @var{cv}. When +thread resumes re-aquire @var{lock}. May signal an error if @var{lock} +is not owned by the current thread. + +@strong{Note:} In some circumstances, the thread may wake up even if no +call to @coderef{mp:condition-variable-signal} or +@coderef{mp:condition-variable-broadcast} has happened. It is +recommended to check for the condition that triggered the wait in a loop +around any @code{mp:condition-variable-wait} call. + +@strong{Note:} While the condition variable is blocked waiting for a +signal or broadcast event, calling @code{mp:condition-variable-wait} +from further threads must be done using the same mutex as that used by +the threads that are already waiting on this condition variable. The +behaviour is undefined if this constraint is violated. @end defun @@ -40,7 +54,8 @@ resumes re-aquire @var{lock}. @defun mp:condition-variable-timedwait cv lock seconds @coderef{mp:condition-variable-wait} which timeouts after @var{seconds} -seconds. +seconds. May signal an error if @var{lock} is not owned by the current +thread. @end defun @@ -51,8 +66,8 @@ seconds. @end deftypefun @defun mp:condition-variable-signal cv -Signal @var{cv} (wakes up only one waiter). After signal, signaling -thread keeps lock, waking thread goes on the queue waiting for the lock. +Wake up at least one of the waiters of @var{cv}. Usually, this will wake +up only a single thread, but it may also wake up multiple threads. See @coderef{mp:condition-variable-wait}. @end defun @@ -65,7 +80,7 @@ See @coderef{mp:condition-variable-wait}. @end deftypefun @defun mp:condition-variable-broadcast cv -Signal @var{cv} (wakes up all waiters). +Wake up all waiters of @var{cv}. See @coderef{mp:condition-variable-wait}. @end defun diff --git a/src/doc/manual/extensions/mp_ref_mutex.txi b/src/doc/manual/extensions/mp_ref_mutex.txi index 4e62dfa86..54710cea5 100644 --- a/src/doc/manual/extensions/mp_ref_mutex.txi +++ b/src/doc/manual/extensions/mp_ref_mutex.txi @@ -67,8 +67,9 @@ Returns the name of @var{lock}. @end deftypefun @defun mp:lock-owner lock -Returns the process owning @var{lock}. For testing whether the current -thread is holding a lock see @coderef{mp:holding-lock-p}. +Returns the process owning @var{lock} or @code{nil} if the mutex is not +owned by any process. For testing whether the current thread +is holding a lock see @coderef{mp:holding-lock-p}. @end defun @@ -79,7 +80,7 @@ thread is holding a lock see @coderef{mp:holding-lock-p}. @end deftypefun @defun mp:lock-count lock -Returns number of processes waiting for @var{lock}. +Returns number of times @var{lock} has been locked. @end defun @@ -101,7 +102,8 @@ returns @code{ECL_NIL}, otherwise @code{ECL_T}. Tries to acquire a lock. @var{wait} indicates whether function should block or give up if @var{lock} is already taken. If @var{wait} is @code{nil} and @var{lock} can't be acquired returns -@code{nil}. Succesful operation returns @code{t}. +@code{nil}. Succesful operation returns @code{t}. Will signal an error +if the mutex is non-recursive and current thread already owns the lock. @end defun @@ -112,15 +114,17 @@ block or give up if @var{lock} is already taken. If @var{wait} is @end deftypefun @defun mp:giveup-lock lock -Releases @var{lock}. +Releases @var{lock} and returns @code{t}. May signal an error if the +lock is not owned by the current thread. @end defun @lspdef mp:with-lock @defmac mp:with-lock (lock-form) &body body -Acquire lock for the dynamic scope of @var{body}, which is executed -with the lock held by current thread. Returns the values of body. +Acquire lock for the dynamic scope of @var{body}, which is executed with +the lock held by current thread. Returns the values of +body. @c (lock-form &key wait-p timeout) diff --git a/src/doc/manual/extensions/mp_ref_process.txi b/src/doc/manual/extensions/mp_ref_process.txi index 1cc61e7c9..3857d1a99 100644 --- a/src/doc/manual/extensions/mp_ref_process.txi +++ b/src/doc/manual/extensions/mp_ref_process.txi @@ -58,6 +58,12 @@ one has to consider: @item Reentrancy: Functions, which usually are not called recursively can be re-entered during execution of the interrupt. @item Stack unwinding: Non-local jumps like @code{throw} or @code{return-from} in the interrupting code will handle @code{unwind-protect} forms like usual. However, the cleanup forms of an @code{unwind-protect} can still be interrupted. In that case the execution flow will jump to the next @code{unwind-protect}. @end itemize +Note also that no guarantees are made that functions from the Common +Lisp standard or ECL extensions are interrupt safe (although most of +them will be). In particular, the compiler (@code{compile} and +@code{compile-file} functions), FFI calls and aquire/release functions +for multithreading synchronization objects like mutexes or condition +variables should not be interrupted by @coderef{mp:interrupt-process}. @exindex Process interruption Example: