[docs] [issue23484] SemLock acquire() keyword arg 'blocking' is invalid

Davin Potts report at bugs.python.org
Thu Mar 26 16:32:40 CET 2015

Davin Potts added the comment:

Attaching patches for 3.5/default, 3.4, and 2.7 which update the documentation on multiprocessing.Lock, RLock, Semaphore, and BoundedSemaphore to describe their actual implemented behavior, replacing the existing, misleading claim that they are clones of threading.Lock, etc., respectively.

Specific changes:
* Lock and RLock now have their acquire and release methods drawn out so as to best explain the significant behavioral differences (versus threading) in return values, potential exceptions being raised, and passing arguments.
* Semaphore and BoundedSemaphore are not as drawn out because their behaviors are indeed the same in every regard except for the difference in block-vs-blocking (and in the case of 2.7, timeout is novel in multiprocessing and doesn't appear until 3.2 in threading).
* In 3.4 and 3.5, the inaccurate note block at the end of the synchronization section no longer misrepresents the treatment of the timeout argument in threading analogs.

It is worth noting that in 3.x, the behavior around the timeout argument in multiprocessing.{Lock,RLock,Semaphore,BoundedSemaphore} already matches that of threading.Semaphore and BoundedSemaphore.  The threading module appears inconsistent in its use of the timeout argument when comparing Semaphore/BoundedSemaphore with Lock/RLock.  It would be interesting to investigate whether in 3.x this inconsistency within threading could be brought in line with the rest of multiprocessing.

In issue21342 the notion of unifying the implementations of these synchronization primitives across threading and multiprocessing is suggested.  If that is pursued, it would reasonably be attempted on default/3.5 and not backported to 2.7 (nor probably 3.4).  Thus this patch to update the documentation is still highly valuable for 2.7 and 3.4 and 3.5 (at least until such time as a unification effort might be undertaken in the case of 3.5).

keywords: +patch
stage: needs patch -> patch review
Added file: http://bugs.python.org/file38702/issue_23484_doc_locks_py35_and_py34.patch

Python tracker <report at bugs.python.org>

More information about the docs mailing list