summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libmutex.tex
blob: d6e3707b5370b2379189533f1a106eb7a5dfe209 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
% LaTeXed from comments in file
\section{\module{mutex} ---
         Mutual exclusion support}

\declaremodule{standard}{mutex}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
\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)
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}