Doc/library/mutex.rst

   1
   2 :mod:`mutex` --- Mutual exclusion support
   3 =========================================
   4
   5 .. module:: mutex
   6    :synopsis: Lock and queue for mutual exclusion.
   7    :deprecated:
   8
   9 .. deprecated::
  10    The :mod:`mutex` module has been removed in Python 3.0.
  11
  12 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
  13
  14
  15 The :mod:`mutex` module defines a class that allows mutual-exclusion via
  16 acquiring and releasing locks. It does not require (or imply)
  17 :mod:`threading` or multi-tasking, though it could be useful for those
  18 purposes.
  19
  20 The :mod:`mutex` module defines the following class:
  21
  22
  23 .. class:: mutex()
  24
  25    Create a new (unlocked) mutex.
  26
  27    A mutex has two pieces of state --- a "locked" bit and a queue. When the mutex
  28    is not locked, the queue is empty. Otherwise, the queue contains zero or more
  29    ``(function, argument)`` pairs representing functions (or methods) waiting to
  30    acquire the lock. When the mutex is unlocked while the queue is not empty, the
  31    first queue entry is removed and its  ``function(argument)`` pair called,
  32    implying it now has the lock.
  33
  34    Of course, no multi-threading is implied -- hence the funny interface for
  35    :meth:`lock`, where a function is called once the lock is acquired.
  36
  37
  38 .. _mutex-objects:
  39
  40 Mutex Objects
  41 -------------
  42
  43 :class:`mutex` objects have following methods:
  44
  45
  46 .. method:: mutex.test()
  47
  48    Check whether the mutex is locked.
  49
  50
  51 .. method:: mutex.testandset()
  52
  53    "Atomic" test-and-set, grab the lock if it is not set, and return ``True``,
  54    otherwise, return ``False``.
  55
  56
  57 .. method:: mutex.lock(function, argument)
  58
  59    Execute ``function(argument)``, unless the mutex is locked. In the case it is
  60    locked, place the function and argument on the queue. See :meth:`unlock` for
  61    explanation of when ``function(argument)`` is executed in that case.
  62
  63
  64 .. method:: mutex.unlock()
  65
  66    Unlock the mutex if queue is empty, otherwise execute the first element in the
  67    queue.
  68