classification
Title: RLock undocumented behavior in case of multiple acquire
Type: Stage:
Components: Documentation, Library (Lib) Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: ahxxm, docs@python, iritkatriel, josh.r, smbrd
Priority: normal Keywords: easy

Created on 2016-03-22 06:56 by smbrd, last changed 2021-06-18 14:35 by iritkatriel.

Repositories containing patches
https://hg.python.org/cpython/rev/020377a15708
Messages (4)
msg262165 - (view) Author: Mateusz (smbrd) Date: 2016-03-22 06:56
The number of acquisitions must be the same as the number of releases or else lock will not be released for other threads leading to deadlock. This is not mentioned in documentation. 

First acquisition returns boolean and further acquisitions return 1. This is also not mentioned in documentation.
msg262231 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2016-03-23 02:49
Per the docs ( https://docs.python.org/3/library/threading.html#rlock-objects ):

"To unlock the lock, a thread calls its release() method. acquire()/release() call pairs may be nested; only the final release() (the release() of the outermost pair) resets the lock to unlocked and allows another thread blocked in acquire() to proceed."

The docs aren't super clear on the return type, but they aren't so overly specified as to make returning either True or 1 incorrect; they use lowercase "true" to describe the return value, which doesn't *have* to mean True, just something that evaluates as truthy.

In 3.5 at least, it looks like both initial and subsequent acquires are all returning True, even when called without passing an argument; this actually violates the docs, which claim that not passing an argument means "There is no return value" (possibly only when there is contended acquisition, the wording is odd), when in fact a no-argument call returns True just like explicitly passing blocking as True.
msg270216 - (view) Author: ahxxm (ahxxm) Date: 2016-07-12 00:31
As seen from commit log, all return type are double back-quoted, this could be a rendering error.

I think this commit somehow makes it clear that RLock is a thread-level reentrant lock, some code example of suggested usage might be helpful though.
msg396068 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-06-18 14:35
The RLock documentation is a bit more verbose than it needs to be (for instance, there is no reason to specify the "no args" case separately from the "blocking=True" case (since True is the default value of blocking).

The issue of balancing acquire/release calls is mentioned as Josh says, but could perhaps be stated more simply as well.
History
Date User Action Args
2021-06-18 14:35:22iritkatrielsetversions: + Python 3.11, - Python 2.7
nosy: + iritkatriel

messages: + msg396068

keywords: + easy
2016-07-12 00:31:53ahxxmsethgrepos: + hgrepo348

messages: + msg270216
nosy: + ahxxm
2016-03-23 02:49:36josh.rsetnosy: + josh.r
messages: + msg262231
2016-03-22 06:56:38smbrdcreate