Because of multithreading semantics, this is not reliable.

[Tim Peters]

[OlafMeding at gmail.com]
> Because of multithreading semantics, this is not reliable.  This
> sentence is found in the Python documentation for "7.8.1 Queue
> Objects".
>
> This scares me!  Why would Queue.qsize(), Queue.empty( ), and a
> Queue.full() not be reliable?

Because they may not be telling the truth at the instant the _caller_
tries to use the result.  I'm not sure why, but people write code like

     if q.empty():
         return

in a thread, and then complain that "it's a bug" if some other thread
of theirs happens to sneak in and add another item to the queue
_between_ the time q.empty() correctly determined that q was empty,
and the time the code generated for "if q.empty()" tests the result. 
There's no mutex to stop other threads from running between those
times.  The docs could be clearer about this, and "not reliable" had a
stronger meaning in earlier versions of Python.

> Looking at the source code of Queue.py, all 3 calls use a mutex (based
> on thread.allocate_lock()).  Does this mean that the
> thread.allocate_lock() mechanism is not reliable (scary indeed)

No.

> or does this have to do with other implementation details?

It just has to do with the way threads work, and with trying to
disabuse newbies of faulty common beliefs.  It's good to scare
threading newbies away from these methods, because they _don't_ do
what newbies typically assume they do.  That puts them in the
"attractive nuisance" category for many people.