classification
Title: Lock.acquire() docs incorrect about negative timeout
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, python-dev, tim.peters
Priority: normal Keywords: easy

Created on 2013-09-04 21:54 by tim.peters, last changed 2013-10-06 08:48 by python-dev. This issue is now closed.

Messages (2)
msg196960 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2013-09-04 21:54
Here from the 3.3.2 docs for threading.Lock:

"""
acquire(blocking=True, timeout=-1) 
Acquire a lock, blocking or non-blocking.

...

When invoked with the floating-point timeout argument set to a positive value, block for at most the number of seconds specified by timeout and as long as the lock cannot be acquired. A negative timeout argument specifies an unbounded wait. 

...

"""

However, that's not what the code does for a negative timeout:

>>> from threading import Lock
>>> x = Lock()
>>> x.acquire(1, -0.2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: timeout value must be strictly positive

The only negative value the code allows is -1, in lock_PyThread_acquire_lock():

    if (timeout < 0 && timeout != -1) {
        PyErr_SetString(PyExc_ValueError, "timeout value must be "
                        "strictly positive");
        return NULL;
    }

The docs should change to say that -1 is special ;-)
msg199055 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-10-06 08:48
New changeset ff5fb419967f by Georg Brandl in branch '3.3':
Closes #18927: Lock.acquire only accepts -1 or positive values for timeout.
http://hg.python.org/cpython/rev/ff5fb419967f
History
Date User Action Args
2013-10-06 08:48:02python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg199055

resolution: fixed
stage: resolved
2013-09-04 21:54:08tim.peterscreate