[docs] Confusing API in Threading module.

[Dong Uk Ju]

Dear Python Managers,


While reading the API for Threading module, I noticed that explanation of Lock.acquire() is really confusing.


Here I attach the original statement.


(Python 2)

Lock.acquire([blocking])<https://docs.python.org/2/library/threading.html#threading.Lock.acquire>

Acquire a lock, blocking or non-blocking.

When invoked with the blocking argument set to True (the default), block until the lock is unlocked, then set it to locked and return True.

When invoked with the blocking argument set to False, do not block. If a call with blocking set to True would block, return False immediately; otherwise, set the lock to locked and return True.


(Python 3)

acquire(blocking=True, timeout=-1)¶<https://docs.python.org/3/library/threading.html#threading.Lock.acquire>

Acquire a lock, blocking or non-blocking.

When invoked with the blocking argument set to True (the default), block until the lock is unlocked, then set it to locked and return True.

When invoked with the blocking argument set to False, do not block. If a call with blocking set to Truewould block, return False immediately; otherwise, set the lock to locked and return True.

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 timeout argument of -1 specifies an unbounded wait. It is forbidden to specify a timeout when blocking is false.

The return value is True if the lock is acquired successfully, False if not (for example if the timeoutexpired).


Both version have statement "When invoked with the blocking argument set to False, do not block. If a call with blocking set to True would block, return False immediately".


The second sentence confuses a lot.


What happen if a call with blocking set to False would block ??

>From my insight, it might also return False immediately and will not block or wait for other working thread.


If my understanding is wrong, prior acquire call's blocking argument matters for later call of acquire.

Then, there should be 4 cases,

1) acquire(True) on acquire(True)

2) acquire(True) on acquire(False)

3) acquire(False) on acquire(True)

4) acquire(False) on acquire(False).


I don't think this works in this way, besides API doesn't specifies those cases.


If my understanding is right,(Prior interpretation is right), I recommend to revise the sentence to "When invoked with the blocking argument set to False, do not block. If acquire() is called with blocking set to False while another thread is working on it(currently locked status), return False immediately."


Please kindly consider this for better python.


Thank you.


Sincerely,

Donguk Ju.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20171218/9ac5a35a/attachment-0001.html>