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/_thread.rst b/Doc/library/_thread.rst
index cb62407..d4ff6de 100644
--- a/Doc/library/_thread.rst
+++ b/Doc/library/_thread.rst
@@ -28,7 +28,7 @@
:mod:`_dummy_thread` module is available. It duplicates this module's interface
and can be used as a drop-in replacement.
-It defines the following constant and functions:
+It defines the following constants and functions:
.. exception:: error
@@ -103,19 +103,34 @@
Availability: Windows, systems with POSIX threads.
+.. data:: TIMEOUT_MAX
+
+ The maximum value allowed for the *timeout* parameter of
+ :meth:`Lock.acquire`. Specifiying a timeout greater than this value will
+ raise an :exc:`OverflowError`.
+
+
Lock objects have the following methods:
-.. method:: lock.acquire([waitflag])
+.. method:: lock.acquire(waitflag=1, timeout=-1)
- Without the optional argument, this method acquires the lock unconditionally, if
+ 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 --- that's their reason for existence). If the integer
- *waitflag* argument is present, the action depends on its value: if it is zero,
- the lock is only acquired if it can be acquired immediately without waiting,
- while if it is nonzero, the lock is acquired unconditionally as before. The
- return value is ``True`` if the lock is acquired successfully, ``False`` if not.
+ time can acquire a lock --- that's their reason for existence).
+ If the integer *waitflag* argument is present, the action depends on its
+ value: if it is zero, the lock is only acquired if it can be acquired
+ immediately without waiting, while if it is nonzero, the lock is acquired
+ unconditionally as above.
+
+ If the floating-point *timeout* argument is present and positive, it
+ specifies the maximum wait time in seconds before returning. A negative
+ *timeout* argument specifies an unbounded wait. You cannot specify
+ a *timeout* if *waitflag* is zero.
+
+ The return value is ``True`` if the lock is acquired successfully,
+ ``False`` if not.
.. method:: lock.release()