Re: pthread fast mutexes

[Kevin Ryde]

Mikael Djurfeldt <address@hidden> writes:
>
> Well, but the past mutexes didn't report an error either.  I've not
> taken away any semantics.

Ah yes.  Ok, below is some words for the manual to try to clarify the
situation.  In particular I take it the current words about mutexes
being recursive applies only to fair mutexes.

(This is also what I threatened about collecting up of all mutex stuff
into one section, instead of spread through three places.)



Mutexes
=======

 - Scheme Procedure: make-mutex
 - Scheme Procedure: make-fair-mutex
     Create a new mutex object.

     A standard mutex (`make-mutex') is fast, but its features are
     minimal.  Recursive locking (multiple lock calls) is not permitted,
     and an unlock can be done only when already locked, and only by the
     owning thread.  When multiple threads are blocked waiting to
     acquire the mutex, it's unspecified which will get it next.

     A fair mutex (`make-fair-mutex') on the other hand has more
     features and error checking.  Recursive locking is allowed, a given
     thread can make multiple lock calls and the mutex is released when
     a balancing number of unlocks are done.  Other threads blocked
     waiting to acquire the mutex form a queue and the one waiting
     longest will be the next to acquire it.

     Note that in both cases there is no protection against a "deadly
     embrace".  For instance currently an endless wait will occur if one
     thread has locked mutex A and is waiting on mutex B, but another
     thread owns B and is waiting on A.  Acquiring requisite mutexes in
     a fixed order (like always A before B) in all threads is one way to
     avoid such problems.

 - Scheme Procedure: lock-mutex mutex
     Lock MUTEX.  If the mutex is already locked by another thread then
     the calling thread is blocked and `lock-mutex' only returns when
     the mutex is acquired and locked.

     For standard mutexes (`make-mutex'), a thread which has locked
     MUTEX must not call `lock-mutex' on it a further time.  Behaviour
     is unspecified if this is done.

     For a fair mutex (`make-fair-mutex'), a thread may call
     `lock-mutex' to lock MUTEX again, this will then require a further
     balancing `unlock-mutex' to release.

     When a system async is activated for a thread blocked in a call to
     `lock-mutex', the waiting is interrupted and the async is
     executed.  When the async returns, the waiting is resumed.

 - Scheme Procedure: try-mutex mutex
     Try to lock MUTEX as per `lock-mutex', but without waiting.  If
     MUTEX can be acquired immediately, this is done and the return is
     `#t'.  If MUTEX is owned by some other thread then nothing is done
     and the return is `#f'.

 - Scheme Procedure: unlock-mutex mutex
     Unlock MUTEX.

     For a standard mutex (`make-mutex'), behaviour is unspecified if
     the calling thread has not locked MUTEX.

     For a fair mutex (`make-fair-mutex'), an error is thrown if the
     calling thread does not own MUTEX.


 - macro: with-mutex mutex [body...]
     Lock MUTEX, evaluate BODY, and then unlock MUTEX.  These
     sub-operations form the branches of a `dynamic-wind', so MUTEX is
     unlocked if an error or new continuation exits BODY, and is
     re-locked if BODY is re-entered by a captured continuation.

 - macro: monitor body...
     Evaluate BODY, with a mutex locked so only one thread can execute
     that code at any one time.  The return value is the return from
     the last form in BODY.

     Each `monitor' form has its own private mutex and the locking is
     done as per `with-mutex' above.  A standard mutex (`make-mutex')
     is used, which means BODY must not recursively re-enter its
     `monitor' form.

     The term "monitor" comes from operating system theory, where it
     means a particular bit of code managing access to some resource and
     which only ever executes on behalf of one process at any one time.


   For C code, the standard mutexes described above can be used with the
following C datatype and functions.

 - C Data Type: scm_t_mutex
     A mutex, to be used with `scm_mutex_init', etc.

 - C Function: void scm_mutex_init (scm_t_mutex *m)
     Initialize the mutex structure pointed to by M.

 - C Function: void scm_mutex_destroy (scm_t_mutex *m)
     Deallocate all resources associated with M.

 - C Function: void scm_mutex_lock (scm_t_mutex *m)
     Lock the mutex M.  When it is already locked by a different
     thread, wait until it becomes available.  Locking a mutex that is
     already locked by the current threads is not allowd and results in
     undefined behavior.  The mutexes are not guaranteed to be fair.
     That is, a thread that attempts a lock after yourself might be
     granted it before you.

 - C Function: int scm_mutex_trylock (scm_t_mutex *m)
     Lock M as per `scm_mutex_lock' but don't wait.  Return non-zero
     when the mutex has been locked, or return zero if it is already
     locked by some other thread.

 - C Function: void scm_mutex_unlock (scm_t_mutex *m)
     Unlock the mutex M.  The mutex must have been locked by the
     current thread, else the behavior is undefined.