Issue #7316: the acquire() method of lock objects in the :mod:`threading`
module now takes an optional timeout argument in seconds. Timeout support
relies on the system threading library, so as to avoid a semi-busy wait
loop.
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index f642111..1f2b763 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -155,6 +155,16 @@
Availability: Windows, systems with POSIX threads.
+This module also defines the following constant:
+
+.. data:: TIMEOUT_MAX
+
+ The maximum value allowed for the *timeout* parameter of blocking functions
+ (:meth:`Lock.acquire`, :meth:`RLock.acquire`, :meth:`Condition.wait`, etc.).
+ Specifiying a timeout greater than this value will raise an
+ :exc:`OverflowError`.
+
+
Detailed interfaces for the objects are documented below.
The design of this module is loosely based on Java's threading model. However,
@@ -349,7 +359,7 @@
All methods are executed atomically.
-.. method:: Lock.acquire(blocking=True)
+.. method:: Lock.acquire(blocking=True, timeout=-1)
Acquire a lock, blocking or non-blocking.
@@ -363,6 +373,15 @@
without an argument would block, return false immediately; otherwise, do the
same thing as when called without arguments, 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 negative *timeout* argument
+ 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 *timeout* expired).
+
.. method:: Lock.release()
@@ -396,7 +415,7 @@
:meth:`acquire` to proceed.
-.. method:: RLock.acquire(blocking=True)
+.. method:: RLock.acquire(blocking=True, timeout=-1)
Acquire a lock, blocking or non-blocking.
@@ -415,6 +434,11 @@
without an argument would block, return false immediately; otherwise, do the
same thing as when called without arguments, 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. Return true if the lock has
+ been acquired, false if the timeout has elapsed.
+
.. method:: RLock.release()