A condition variable returns in two cases: it was
notified by another thread, or it timed out (if a
timeout was specified).  See an example in the popular
Boost C++ library:

http://boost.org/doc/html/condition.html

This patch adds this capability to the Python
threading.Condition.wait() method, which used to return
nothing.  I added the relevant couple of lines to the
documentaion as well (see patch).

(An example is using a condition variable as a sentinel
for exiting a loop or a polling thread.  Using the
return value one can decide whether to exit the loop or
not.)