doc: multithreading: clarify restrictions for mutex functions

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

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)
 

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: