Fred Drake | 2231357 | 1999-06-27 15:00:41 +0000 | [diff] [blame] | 1 | \section{\module{mutex} --- |
| 2 | Mutual exclusion support} |
| 3 | |
| 4 | \declaremodule{standard}{mutex} |
Fred Drake | 57657bc | 2000-12-01 15:25:23 +0000 | [diff] [blame] | 5 | \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} |
Fred Drake | 2231357 | 1999-06-27 15:00:41 +0000 | [diff] [blame] | 6 | \modulesynopsis{Lock and queue for mutual exclusion.} |
| 7 | |
Fred Drake | 986eafd | 2001-01-09 20:54:15 +0000 | [diff] [blame] | 8 | The \module{mutex} module defines a class that allows mutual-exclusion |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 9 | via acquiring and releasing locks. It does not require (or imply) |
Fred Drake | 4886c66 | 1999-06-29 14:57:12 +0000 | [diff] [blame] | 10 | threading or multi-tasking, though it could be useful for |
Fred Drake | 2231357 | 1999-06-27 15:00:41 +0000 | [diff] [blame] | 11 | those purposes. |
| 12 | |
| 13 | The \module{mutex} module defines the following class: |
| 14 | |
| 15 | \begin{classdesc}{mutex}{} |
| 16 | Create a new (unlocked) mutex. |
| 17 | |
| 18 | A mutex has two pieces of state --- a ``locked'' bit and a queue. |
| 19 | When the mutex is not locked, the queue is empty. |
Fred Drake | 986eafd | 2001-01-09 20:54:15 +0000 | [diff] [blame] | 20 | Otherwise, the queue contains zero or more |
Fred Drake | 2231357 | 1999-06-27 15:00:41 +0000 | [diff] [blame] | 21 | \code{(\var{function}, \var{argument})} pairs |
| 22 | representing functions (or methods) waiting to acquire the lock. |
| 23 | When the mutex is unlocked while the queue is not empty, |
| 24 | the first queue entry is removed and its |
| 25 | \code{\var{function}(\var{argument})} pair called, |
| 26 | implying it now has the lock. |
| 27 | |
| 28 | Of course, no multi-threading is implied -- hence the funny interface |
Fred Drake | 986eafd | 2001-01-09 20:54:15 +0000 | [diff] [blame] | 29 | for \method{lock()}, where a function is called once the lock is |
| 30 | acquired. |
Fred Drake | 2231357 | 1999-06-27 15:00:41 +0000 | [diff] [blame] | 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, |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 44 | and return \code{True}, otherwise, return \code{False}. |
Fred Drake | 2231357 | 1999-06-27 15:00:41 +0000 | [diff] [blame] | 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} |