>>> import mutex
    >>> print mutex.mutex.testandset.__doc__
    Atomic test-and-set -- grab the lock if it is not set,
            return True if it succeeded.


The above docstring is wrong: the method is not atomic.  This is easy to see by inspecting the method's code:

    def testandset(self):
        """Atomic test-and-set -- grab the lock if it is not set,
        return True if it succeeded."""
        if not self.locked:
            self.locked = 1
            return True
        else:
            return False

Therefore, it is possible for two threads to lock the same mutex simultaneously.  So the mutex module cannot be used for mutual exclusion.

The documentation for mutex says "The mutex module defines a class that allows mutual-exclusion via acquiring and releasing locks."  [http://docs.python.org/lib/module-mutex.html].  Perhaps it would be a good idea to make the module actually do what the documentation says.

Hi David,
I just fired up the docs and found this:
"The 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 docs dont say about threads using mutex object, but instead say if you want to use threading you can use mutex obj.

How are you using mutex with threads, can you please provide some information.

If muobj is an instance of mutex class.
muobj.testandset() for process-a will set the lock.
muobj.testandset() for process-b will be dealt with self.lock = True and wont be able to set.

> How are you using mutex with threads, can you please provide some
information.

I'm attaching an example program that demonstrates two threads both locking the same mutex at the same time.

> If muobj is an instance of mutex class.
> muobj.testandset() for process-a will set the lock.
> muobj.testandset() for process-b will be dealt with self.lock = True and
> wont be able to set.

That isn't correct.  It is possible for testandset to return True in both thread-a and thread-b.  What can happen is the following:

1) Thread a calls testandset().  It executes the line "if not self.locked", and finds the result to be True.
2) The OS switches threads.
3) Thread b calls testandset().  It executes the line "if not self.locked", and finds the result to be True.
4) Thread b sets "self.locked = 1" and returns True
5) Thread a sets "self.locked = 1" and returns True
File Added: ex.py

Thanks David, there is something 'interesting' being observed here.
At a point:
Calling testandset in thread 1, m.locked is False
Calling testandset in thread 0, m.locked is False
Thread 0 locked
Resetting, trying again

Another place:
Calling testandset in thread 1, m.locked is False
Calling testandset in thread 0, m.locked is False
Thread 0 locked
Thread 1 locked
Hah, all these threads locked at the same time: [0, 1]

My doubts are still with threading, but am unable to derive anything.
Should someone more experienced look into? Or mind taking this for suggestions to c.l.p?

I've attached a patch to mutex.py that fixes the bug by acquiring a lock in testandset() and unlock().  After you apply the patch, the previous attachment will run forever.
File Added: patch.txt

The docs may be misleading - they're missing a key comment from the source code that suggests that this particular mutex is specifically for use with the single threaded event scheduler in the sched module. On the other hand, the module predates the thread module by more than a year, and the threading module by about 7 years, so it may simply have failed to keep up with the times.

The module as written definitely isn't thread-safe though (I suspect the question of whether or not it should be hasn't really come up before, as most new code just uses threading.Lock or threading.RLock for all its mutex needs). Either the code needs to change or the docs - this question would probably be best asked on python-dev (referencing this bug report).

Making the mutex module thread safe is a low hanging fruit for the bug
day. *wink*

> Making the mutex module thread safe is a low hanging fruit for the bug
day.

But would it bring anything that the threading module doesn't have?

I tested the patch and I found an error. It was missing a line "if 
call:" in the unlock function. I added it, and tested again with the 
ex.py example and it didn't found any threads locked at the same time.

Is this module still of any use to anyone? It seems if you wanted a fake
mutex, you could just import LockType from dummy_thread.

On 2008/2/23, Guido van Rossum said in python-dev

> According to the docstring it's only meant to be used with sched.py.
> Please don't try to make it work with threads!

Anyway, this module will be removed, or at least its API hidden, in 3.0.

For what it's worth, here's a test case against the trunk.

Added test case in r61024.