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: Lock Objects documentation clarification
Type: Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6, Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benjamin.peterson, docs@python, rhettinger, ulrich.stern
Priority: low Keywords:

Created on 2018-10-02 23:41 by ulrich.stern, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (4)
msg326926 - (view) Author: (ulrich.stern) Date: 2018-10-02 23:41
The first sentence of the documentation for Lock Objects (https://docs.python.org/2/library/threading.html#lock-objects) seems incorrect.  It currently states "A primitive lock is a synchronization primitive that is not owned by a particular thread when locked."  The "not" should be deleted.  (Alternatively, one could change "locked" to "unlocked.")
msg326932 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2018-10-03 04:48
The current documentation is correct. While conceptually one may think of a lock as being held ("owned") by a particular thread, the lock internally has no idea what thread owns it—operations on a lock are influenced only by its current state not what thread is performing the operation. It's perfectly possible, if inadvisable, to release a lock on a thread different from the one it was acquired on. The description of ownership is meant to draw a distinction with recursive locks, which do have an internal notion of ownership.
msg327058 - (view) Author: (ulrich.stern) Date: 2018-10-04 15:44
I still think the documentation should be changed, and an improved version would look more like your comment than what it looks now.  I assume to most people "owning" means exclusively holding the lock, and a particular thread can do this for Lock Objects.  For example, here what my #1 Google result for "lock ownership" (https://www.justsoftwaresolutions.co.uk/threading/locks-mutexes-semaphores.html) says:

> What it means to "own" a lock depends on the precise type of the lockable object. For some lockable objects...  In other cases, the definition is more fluid, and the ownership of the lock is more conceptual. In these cases, ownership can be relinquished by a different thread or object than the thread or object that acquired the lock.

In my opinion, the Python documentation currently takes the unusual point of view "a thread cannot 'own' a lock since it could be 'stolen' (released) by another thread."  And the Lock Objects documentation has no explanation for this view, which makes it possibly confusing.  Since multithreading is often tricky, documentation improvement seems worthwhile.  Happy to propose wording that incorporates our discussion if you are interested.
msg327477 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-10-10 14:35
I concur with Benjamin that the docs are reasonable as-is.
History
Date User Action Args
2022-04-11 14:59:06adminsetgithub: 79059
2018-10-10 14:35:13rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg327477

resolution: rejected
2018-10-10 03:45:09benjamin.petersonsetpriority: normal -> low
status: closed -> open
resolution: not a bug -> (no value)
title: Lock Objects documentation bug -> Lock Objects documentation clarification
2018-10-04 15:44:12ulrich.sternsetmessages: + msg327058
2018-10-03 04:48:40benjamin.petersonsetstatus: open -> closed

nosy: + benjamin.peterson
messages: + msg326932

resolution: not a bug
stage: resolved
2018-10-02 23:41:46ulrich.sterncreate