\section{\module{mutex} ---

Mutual exclusion support}

\declaremodule{standard}{mutex}

\sectionauthor{Moshe Zadka}{[email protected]}

\modulesynopsis{Lock and queue for mutual exclusion.}

The \module{mutex} defines a class that allows mutual-exclusion

via aquiring and releasing locks. It does not require (or imply)

and threading or multi-tasking, though it could be useful for

those purposes.

The \module{mutex} module defines the following class:

\begin{classdesc}{mutex}{}

Create a new (unlocked) mutex.

A mutex has two pieces of state --- a ``locked'' bit and a queue.

When the mutex is not locked, the queue is empty.

Otherwise, the queue contains 0 or more

\code{(\var{function}, \var{argument})} pairs

representing functions (or methods) waiting to acquire the lock.

When the mutex is unlocked while the queue is not empty,

the first queue entry is removed and its

\code{\var{function}(\var{argument})} pair called,

implying it now has the lock.

Of course, no multi-threading is implied -- hence the funny interface

for lock, where a function is called once the lock is aquired.

\end{classdesc}

\subsection{Mutex Objects \label{mutex-objects}}

\class{mutex} objects have following methods:

\begin{methoddesc}{test}{}

Check whether the mutex is locked.

\end{methoddesc}

\begin{methoddesc}{testandset}{}

``Atomic'' test-and-set, grab the lock if it is not set,

and return true, otherwise, return false.

\end{methoddesc}

\begin{methoddesc}{lock}{function, argument}

Execute \code{\var{function}(\var{argument})}, unless the mutex is locked.

In the case it is locked, place the function and argument on the queue.

See \method{unlock} for explanation of when

\code{\var{function}(\var{argument})} is executed in that case.

\end{methoddesc}

\begin{methoddesc}{unlock}{}

Unlock the mutex if queue is empty, otherwise execute the first element

in the queue.

\end{methoddesc}