diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/_thread.rst | 31 | ||||
| -rw-r--r-- | Doc/library/threading.rst | 28 |
2 files changed, 49 insertions, 10 deletions
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 @@ implementation. For systems lacking the :mod:`_thread` module, the :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 @@ It defines the following constant and functions: 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() 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 @@ This module defines the following functions and objects: 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 @@ and may vary across implementations. 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 @@ All methods are executed atomically. 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 @@ pair) resets the lock to unlocked and allows another thread blocked in :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 @@ pair) resets the lock to unlocked and allows another thread blocked in 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() |