This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Documentation for Event.wait return value is either wrong or incomplete
Type: behavior Stage: resolved
Components: Library (Lib) Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, neologix, pitrou, python-dev, r.david.murray, tim.peters
Priority: normal Keywords: patch

Created on 2011-11-29 20:45 by r.david.murray, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
event_wait_cleared.diff neologix, 2011-12-07 18:45 review
event_wait_cleared-1.diff neologix, 2011-12-10 12:55 review
Messages (12)
msg148604 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-11-29 20:45
The documentation for Event.wait says:

  This method returns the internal flag on exit, so it will always return True except if a timeout is given and the operation times out.

In fact, however, if the thread that sets the flag immediately clears it, wait will return False.  Antoine looking at the code says that this appears to be intentional, and that would make sense since originally wait returned no value.

My use case is one thread waiting on another to complete a work loop.  Normally the worker thread goes to sleep after clearing the flag, but sometimes it immediately starts a new work loop.  In either case I want the monitoring loop to take an action when the work loop completes, and raise an error if the wait times out.  It looked to me like Event.wait would work in the scenario.
msg148606 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-11-29 20:50
Thinking about it, if the flag's state if the wait does not expire is not guaranteed to be True, then what I really need is some way to know, when the wait call completes, whether or not it terminated because of a timeout or not.  I can always query the value of the flag separately if its value can in any case be changed by another thread.

I am perhaps using the wrong tool, I'll have to look at the docs further.
msg148608 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-11-29 20:55
Ok, so digging a bit, the feature dates back to issue1674032. 
Interestingly, the OP in that issue had already envisioned that race condition and had precisely proposed the feature to avoid it: “Note that in the above case, the event could be cleared between the return from x.wait and the execution of x.isSet (in another thread), and so this would operate as though x.wait had just timed out”.

So I'm changing my mind and saying it seems desireable to return True if the wait succeeded before the timeout's end, even though the flag may have been reset in the meantime.
In 3.2, Condition.wait also returns a boolean, meaning the check in Event.wait can be atomic.
msg148610 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-11-29 21:00
Changing the title and component to reflect Antoine's new understanding :)
msg148641 - (view) Author: Charles-François Natali (neologix) * (Python committer) Date: 2011-11-30 07:44
> So I'm changing my mind and saying it seems desireable to return True if the wait succeeded before the timeout's end, even though the flag may have been reset in the meantime.

Agreed. What matters is that the event has been signaled, not that
it's currently signaled.
msg148984 - (view) Author: Charles-François Natali (neologix) * (Python committer) Date: 2011-12-07 18:45
Here's a patch.
msg149018 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-12-08 04:29
On Wed, 07 Dec 2011 18:45:27 +0000, <report@bugs.python.org> wrote:
> _______________________________________
> diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
> --- a/Doc/library/threading.rst
> +++ b/Doc/library/threading.rst
> @@ -804,8 +804,9 @@
>        floating point number specifying a timeout for the operation in seconds
>        (or fractions thereof).
>  
> -      This method returns the internal flag on exit, so it will always return
> -      ``True`` except if a timeout is given and the operation times out.
> +      This method returns true if and only if the internal flag has been set to
> +      true by another thread, so it will always return ``True`` except if a
> +      timeout is given and the operation times out.

This seems to imply that if the current thread previously set the event,
the wait will return False, which is contradicted by the 'so' statement
(which appears to be correct).

--David
msg149019 - (view) Author: Charles-François Natali (neologix) * (Python committer) Date: 2011-12-08 07:39
> This seems to imply that if the current thread previously set the event,
> the wait will return False, which is contradicted by the 'so' statement
> (which appears to be correct).

You're probably referring to the "another thread" part...
A suggestion ? I see you're a native speaker :-)
msg149130 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-12-09 22:03
"set to True, either before the wait call or after the wait starts"
msg149150 - (view) Author: Charles-François Natali (neologix) * (Python committer) Date: 2011-12-10 12:55
Thanks, here's a patch updated accordingly.
msg149160 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-12-10 14:23
LGTM.
msg150809 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-01-07 17:27
New changeset eb39d862a250 by Charles-François Natali in branch '3.2':
Issue #13502: threading: Fix a race condition in Event.wait() that made it
http://hg.python.org/cpython/rev/eb39d862a250

New changeset 0fe63bb20e74 by Charles-François Natali in branch 'default':
Issue #13502: threading: Fix a race condition in Event.wait() that made it
http://hg.python.org/cpython/rev/0fe63bb20e74
History
Date User Action Args
2022-04-11 14:57:24adminsetgithub: 57711
2012-01-07 19:40:56neologixsetstatus: open -> closed
resolution: fixed
stage: needs patch -> resolved
2012-01-07 17:27:06python-devsetnosy: + python-dev
messages: + msg150809
2011-12-10 14:23:58r.david.murraysetmessages: + msg149160
2011-12-10 12:55:55neologixsetfiles: + event_wait_cleared-1.diff

messages: + msg149150
2011-12-09 22:03:25r.david.murraysetmessages: + msg149130
2011-12-08 07:39:58neologixsetmessages: + msg149019
2011-12-08 04:30:00r.david.murraysetmessages: + msg149018
2011-12-07 18:45:26neologixsetfiles: + event_wait_cleared.diff
keywords: + patch
messages: + msg148984
2011-11-30 07:44:31neologixsetmessages: + msg148641
title: Event.wait sometimes returns False even when no timeout has occurred -> Documentation for Event.wait return value is either wrong or incomplete
2011-11-29 21:00:43r.david.murraysetmessages: + msg148610
components: + Library (Lib), - Documentation
title: Documentation for Event.wait return value is either wrong or incomplete -> Event.wait sometimes returns False even when no timeout has occurred
2011-11-29 20:55:53pitrousetnosy: + neologix
messages: + msg148608
2011-11-29 20:50:56r.david.murraysetmessages: + msg148606
2011-11-29 20:45:15r.david.murraycreate