Doc/lib/libmutex.tex

   1 % LaTeXed from comments in file
   2 \section{\module{mutex} ---
   3          Mutual exclusion support}
   4
   5 \declaremodule{standard}{mutex}
   6 \sectionauthor{Moshe Zadka}{mzadka@geocities.com}
   7 \modulesynopsis{Lock and queue for mutual exclusion.}
   8
   9 The \module{mutex} defines a class that allows mutual-exclusion
  10 via aquiring and releasing locks. It does not require (or imply)
  11 threading or multi-tasking, though it could be useful for
  12 those purposes.
  13
  14 The \module{mutex} module defines the following class:
  15
  16 \begin{classdesc}{mutex}{}
  17 Create a new (unlocked) mutex.
  18
  19 A mutex has two pieces of state --- a ``locked'' bit and a queue.
  20 When the mutex is not locked, the queue is empty.
  21 Otherwise, the queue contains 0 or more
  22 \code{(\var{function}, \var{argument})} pairs
  23 representing functions (or methods) waiting to acquire the lock.
  24 When the mutex is unlocked while the queue is not empty,
  25 the first queue entry is removed and its
  26 \code{\var{function}(\var{argument})} pair called,
  27 implying it now has the lock.
  28
  29 Of course, no multi-threading is implied -- hence the funny interface
  30 for lock, where a function is called once the lock is aquired.
  31 \end{classdesc}
  32
  33
  34 \subsection{Mutex Objects \label{mutex-objects}}
  35
  36 \class{mutex} objects have following methods:
  37
  38 \begin{methoddesc}{test}{}
  39 Check whether the mutex is locked.
  40 \end{methoddesc}
  41
  42 \begin{methoddesc}{testandset}{}
  43 ``Atomic'' test-and-set, grab the lock if it is not set,
  44 and return true, otherwise, return false.
  45 \end{methoddesc}
  46
  47 \begin{methoddesc}{lock}{function, argument}
  48 Execute \code{\var{function}(\var{argument})}, unless the mutex is locked.
  49 In the case it is locked, place the function and argument on the queue.
  50 See \method{unlock} for explanation of when
  51 \code{\var{function}(\var{argument})} is executed in that case.
  52 \end{methoddesc}
  53
  54 \begin{methoddesc}{unlock}{}
  55 Unlock the mutex if queue is empty, otherwise execute the first element
  56 in the queue.
  57 \end{methoddesc}