| msg187945 - (view) |
Author: Andriy Mysyk (amysyk) * |
Date: 2013-04-27 22:58 |
| Use _thread.Lock.acquire() documentation for threading.Lock.acquire(). threading.Lock inherits acquire() method from _thread.Lock. The two acquire() methods are identical in their functionality yet have different documentation. Documentation for threading.Lock.acquire() creates the impression that the function is more complex or harder to use than it actually is. See http://docs.python.org/devguide/documenting.html#economy-of-expression for guidelines. |
|
|
| msg187946 - (view) |
Author: Andriy Mysyk (amysyk) * |
Date: 2013-04-27 23:02 |
| I am attaching a patch that applies _thread.Lock.acquire() documentation to the functionally identical threading.Lock.acquire(). |
|
|
| msg187947 - (view) |
Author: R. David Murray (r.david.murray) *  |
Date: 2013-04-27 23:35 |
| For the record, both the _thread docs and the threading docs for acquire were updated in 01d1fd775d16 as part of issue 7316. Some at least of the differences come from 6ab4128acccc (issue 14823). That makes it likely that the threading docs are the better of the two. |
|
|
| msg187948 - (view) |
Author: Andriy Mysyk (amysyk) * |
Date: 2013-04-27 23:51 |
| Issue 14823 indeed improved threading documentation. However, even with the improvement threading documentation makes acquire() appear to be more complex and harder to use than it actually is. |
|
|
| msg187965 - (view) |
Author: Georg Brandl (georg.brandl) * |
Date: 2013-04-28 06:02 |
| This patch includes changes from #17851, please remove that (but you can remove the comma after "block"). |
|
|
| msg188004 - (view) |
Author: Andriy Mysyk (amysyk) * |
Date: 2013-04-28 17:02 |
| Apologies. I did not mean to include 17851 changes. Removed the changes, leaving out the comma after "block" in the attached patch. |
|
|
| msg188450 - (view) |
Author: Andriy Mysyk (amysyk) * |
Date: 2013-05-05 17:10 |
| Made changes suggested by Ezio Melotti in the attached patch. |
|
|
| msg188717 - (view) |
Author: R. David Murray (r.david.murray) * |
Date: 2013-05-08 11:39 |
| Added review comments with suggestions on improving the wording further. Once we agree on wording we could apply this to the _thread docs as well, I suppose. Ah, I see that one of the changes I found problematic was suggested by Ezio :) |
|
|
| msg188781 - (view) |
Author: Andriy Mysyk (amysyk) * |
Date: 2013-05-09 15:19 |
| Incorporated R. David Murray's feedback... .. method:: acquire(blocking=True, timeout=-1) Without any optional argument, this method acquires the lock unconditionally, if necessary waiting until it is released by another thread (only one thread at a time can acquire a lock). If *blocking* is ``False``, the call returns immediately. If *blocking* is ``True``, the lock is acquired unconditionally. In both cases the return value indicates whether or not the lock was acquired. If the floating-point *timeout* argument is present and positive, it specifies the maximum wait time in seconds before returning; the return value indicates whether or not the lock was acquired. A negative *timeout* argument specifies an unbounded wait and is the same as not specifying a *timeout* and also setting *blocking* to ``True``. A zero *timeout* is the same as not specifying a *timeout* and setting *blocking* to ``False``. You cannot specify a *timeout* if *blocking* is ``False``. The return value is ``True`` if the lock is acquired successfully, ``False`` if not. |
|
|