Doc/library/mutex.rst

:mod:`mutex` --- Mutual exclusion support
=========================================

.. module:: mutex
   :synopsis: Lock and queue for mutual exclusion.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>


The :mod:`mutex` module defines a class that allows mutual-exclusion via
acquiring and releasing locks. It does not require (or imply) threading or
multi-tasking, though it could be useful for those purposes.

The :mod:`mutex` module defines the following class:


.. class:: 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 zero or more
   ``(function, 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  ``function(argument)`` pair called,
   implying it now has the lock.

   Of course, no multi-threading is implied -- hence the funny interface for
   :meth:`lock`, where a function is called once the lock is acquired.


.. _mutex-objects:

Mutex Objects
-------------

:class:`mutex` objects have following methods:


.. method:: mutex.test()

   Check whether the mutex is locked.


.. method:: mutex.testandset()

   "Atomic" test-and-set, grab the lock if it is not set, and return ``True``,
   otherwise, return ``False``.


.. method:: mutex.lock(function, argument)

   Execute ``function(argument)``, unless the mutex is locked. In the case it is
   locked, place the function and argument on the queue. See :meth:`unlock` for
   explanation of when ``function(argument)`` is executed in that case.


.. method:: mutex.unlock()

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